Overview
<sp-checkbox>
allow users to select multiple items from a list of independent
options, or to mark an individual option as selected.
Should I use a checkbox or a switch? Use a switch when activating something
instead of selecting.
Usage

yarn add @spectrum-web-components/checkbox
Import the side effectful registration of <sp-checkbox>
via:
import '@spectrum-web-components/checkbox/sp-checkbox.js';
When looking to leverage the Checkbox
base class as a type and/or for extension purposes, do so via:
import { Checkbox } from '@spectrum-web-components/checkbox';
Anatomy
A checkbox consists of a box that can be checked or unchecked, and a label that describes its purpose. The checkbox can also be in an indeterminate state, which is visually distinct from both checked and unchecked states.
Options
Sizes
Small
<sp-field-group horizontal label="Small Checkboxes">
<sp-checkbox size="s">Small</sp-checkbox>
<sp-checkbox size="s" checked>Small Checked</sp-checkbox>
<sp-checkbox size="s" indeterminate>Small Indeterminate</sp-checkbox>
</sp-field-group>
Medium
<sp-field-group horizontal label="Medium Checkboxes">
<sp-checkbox size="m">Medium</sp-checkbox>
<sp-checkbox size="m" checked>Medium Checked</sp-checkbox>
<sp-checkbox size="m" indeterminate>Medium Indeterminate</sp-checkbox>
</sp-field-group>
Large
<sp-field-group horizontal label="Large Checkboxes">
<sp-checkbox size="l">Large</sp-checkbox>
<sp-checkbox size="l" checked>Large Checked</sp-checkbox>
<sp-checkbox size="l" indeterminate>Large Indeterminate</sp-checkbox>
</sp-field-group>
Extra Large
<sp-field-group horizontal label="Extra Large Checkboxes">
<sp-checkbox size="xl">Extra Large</sp-checkbox>
<sp-checkbox size="xl" checked>Extra Large Checked</sp-checkbox>
<sp-checkbox size="xl" indeterminate>Extra Large Indeterminate</sp-checkbox>
</sp-field-group>
Variants
Standard Checkboxes
Standard checkboxes are the default style for checkboxes. They are optimal for
application panels where all visual elements are monochrome in order to direct
focus to the content.
<div style="display: flex; justify-content: space-between;">
<div style="display: flex; flex-direction: column;">
<h4 class="spectrum-Heading--subtitle1">Default</h4>
<sp-checkbox>Web component</sp-checkbox>
<sp-checkbox checked>Web component</sp-checkbox>
<sp-checkbox indeterminate>Web component</sp-checkbox>
</div>
<div style="display: flex; flex-direction: column;">
<h4 class="spectrum-Heading--subtitle1">Invalid</h4>
<sp-checkbox invalid>Web component</sp-checkbox>
<sp-checkbox checked invalid>Web component</sp-checkbox>
<sp-checkbox indeterminate invalid>Web component</sp-checkbox>
</div>
<div style="display: flex; flex-direction: column;">
<h4 class="spectrum-Heading--subtitle1">Disabled</h4>
<sp-checkbox disabled>Web component</sp-checkbox>
<sp-checkbox checked disabled>Web component</sp-checkbox>
<sp-checkbox indeterminate disabled>Web component</sp-checkbox>
</div>
</div>
Emphasized Checkboxes
Emphasized checkboxes are a secondary style for checkboxes. The blue color
provides a visual prominence that is optimal for forms, settings, lists or grids
of assets, etc. where the checkboxes need to be noticed.
<div style="display: flex; justify-content: space-between;">
<div style="display: flex; flex-direction: column;">
<h4 class="spectrum-Heading--subtitle1">Default</h4>
<sp-checkbox emphasized>Web component</sp-checkbox>
<sp-checkbox emphasized checked>Web component</sp-checkbox>
<sp-checkbox emphasized indeterminate>Web component</sp-checkbox>
</div>
<div style="display: flex; flex-direction: column;">
<h4 class="spectrum-Heading--subtitle1">Invalid</h4>
<sp-checkbox emphasized invalid>Web component</sp-checkbox>
<sp-checkbox emphasized checked invalid>Web component</sp-checkbox>
<sp-checkbox emphasized indeterminate invalid>
Web component
</sp-checkbox>
</div>
<div style="display: flex; flex-direction: column;">
<h4 class="spectrum-Heading--subtitle1">Disabled</h4>
<sp-checkbox emphasized disabled>Web component</sp-checkbox>
<sp-checkbox emphasized checked disabled>Web component</sp-checkbox>
<sp-checkbox emphasized indeterminate disabled>
Web component
</sp-checkbox>
</div>
</div>
States
Invalid
The invalid
attribute indicates that the checkbox's value is invalid. When set, appropriate ARIA attributes will be automatically applied.
<sp-checkbox invalid>Invalid</sp-checkbox>
Disabled
The disabled
attribute prevents the checkbox from receiving focus or events. The checkbox will appear faded.
<sp-checkbox disabled>Disabled</sp-checkbox>
Indeterminate
The indeterminate
attribute sets the checkbox to an indeterminate state, visually distinct from both checked and unchecked states.
<sp-checkbox indeterminate>Indeterminate</sp-checkbox>
Read-only
Checkboxes have a readonly
attribute for when they’re in the disabled state but still need their labels to be shown. This allows for content to be copied, but not interacted with or changed.
<sp-checkbox readonly>Read-only</sp-checkbox>
Behaviors
Handling events
Event handlers for clicks and other user actions can be registered on an <sp-checkbox>
as they would a standard <input type="checkbox">
element.
<sp-checkbox
id="checkbox-example"
onclick="spAlert(this, '<sp-checkbox> clicked!')"
>
Check this box to see an onclick alert.
</sp-checkbox>
Accessibility
Checkboxes are accessible by default, rendered in HTML using the <input type="checkbox">
element. When the checkbox is set as indeterminate
or
invalid
, the appropriate ARIA state attribute will automatically be applied.
Include a label
Every checkbox must have a label that clearly describes its purpose. The label can be provided as content within the <sp-checkbox>
element.
<sp-checkbox>Send me text messages.</sp-checkbox>
Label groups of related checkboxes
Sets of checkboxes should always have a clear label that describes what the list of options represents and guides users what to do. This is important for accessibility, since a screen reader will read the label before each option. (See field group's label documentation for more information.)
<sp-field-group label="Select your toppings">
<sp-checkbox>Ketchup</sp-checkbox>
<sp-checkbox>Mustard</sp-checkbox>
<sp-checkbox>Pickles</sp-checkbox>
</sp-field-group>
Keyboard Navigation
Checkboxes can be toggled using the Space key when focused. They follow the standard tab order of the page.
Screen readers
Screen readers interpret checkboxes by announcing their role, label, current state, and role to the user. This allows users relying on assistive technology to understand and interact with the checkbox effectively.
When focused, a screen reader will announce:
- The label (text provided inside the or associated with it)
- The state: "checked", "not checked", or "partially checked" (when indeterminate is set)
- The role: "checkbox"
- If the checkbox is marked as invalid, it may also announce "invalid entry" depending on the screen reader.
1.7.0 (2025-06-11)
Minor Changes
sp-overlay: Fixed : Overlays (like pickers and action menus) were incorrectly closing when scrolling occurred within components. The fix ensures the handleScroll
method in OverlayStack
only responds to document/body scrolling events and ignores component-level scrolling events, which was the original intention.
sp-card: Fixed: On mobile Chrome (both Android and iOS), scrolling on sp-card
components would inadvertently trigger click events. This was caused by the timing-based click detection (200ms threshold) in the pointer event handling, which could misinterpret quick scrolls as clicks. This issue did not affect Safari on mobile devices.
sp-action-button: - Fixed : Action buttons with href attributes now properly detects modifier keys and skips the proxy click, allowing only native browser behavior to proceed.
Patch Changes
sp-styles: Remove unnecessary system theme references to reduce complexity for components that don't need the additional mapping layer.
sp-card: - Fixed: sp-card
component relies on sp-popover
for certain toggle interactive behaviors, but this dependency was missing from its dependency tree.
sp-menu: Fixes: Icons in menu stories weren't properly responding to theme changes when used in functional story components.
Switching to class-based LitElement components ensures proper component lifecycle hooks and shadow DOM context for icon initialization and theme integration.
sp-tabs: Added @spectrum-web-components/action-button
as a dependency for Tabs as its used in the direction button.
sp-split-view: Added @spectrum-web-components/shared dependency in splitview since it uses ranDomId from the shared package
sp-textfield: Replace deprecated word-break: break-word
with overflow-wrap: break-word
to align with modern CSS standards and improve cross-browser compatibility. This property was deprecated in Chrome 44 (July 2015) in favor of the standardized overflow-wrap
property.